产品管理 | 文档中心

一、应用场景

产品是设备的集合，通常是一组具有相同功能定义（物模型）的设备集合。例如，产品指同一个型号的产品，设备就是该型号下的某个设备。开发者可通过本服务提供的接口获取到平台产品相关信息，包括产品列表，产品详情、产品物模型信息等。
开发者需要查询具体的产品相关信息时，可通过本服务获取到产品列表，获取产品ID后，查询具体产品的详情、物模型信息。

二、功能说明

本服务提供获取产品列表、获取产品、获取产品物模型信息以及物模型用途和用法的能力，开发者在获取到相应授权前提下，可使用本服务获取产品相关信息，辅助开发者完成业务构建。

三、前提条件

参考《创建产品》，完成创建产品流程。
参考《物模型定义》，完成物模型定义流程。
用户授权

四、关键流程

4.1 创建产品流程

参考《创建产品》完成创建产品流程，详细流程本文略。

登录平台并进入创建产品页面
填写产品信息
创建物模型
完成产品创建

流程说明： 用户在管理平台创建产品，填写产品名称、所属平台、产品型号、产品分类、OS类型、节点类型、连网方式、设备接入协议、第三方生态设备、对用户可见等表单信息。其中设备接入协议中选项V6.5协议是物模型设备接入协议，V6.0协议是数据端点接入协议 （V6.0协议只支持设备属性上报）。

4.2 创建物模型流程

参考《物模型定义》完成物模型定义流程，详细流程本文略。

创建产品页或产品信息页
匹配物模型或自定义物模型（包含如下流程：选择属性、自定义属性、添加事件、添加服务）
完成物模型创建

流程说明： 用户在管理平台可在产品创建流程中完成物模型创建，另可在产品信息页完成物模型创建。V6.0设备协议只支持设备属性上报。

4.3 Token获取

五、API列表

5.1获取产品

5.1.1 查看产品信息

接口描述

应用场景: 提供给其他终端（例如：APP，PC端）展示产品信息。

接口限制：B端用户权限。

返回信息：产品基础信息，产品的设备类型，是否网关设备，产品下设备总数等。

请求方式

GET

请求地址

/v2/product/{product_id}

请求头

名称	必填	类型	备注
Access-Token	true	String	访问Token（B端用户权限）
Content-Type	true	String	application/json

请求参数

名称	必填	类型	备注
-	-	-	-

请求示例：

无

返回参数说明

名称	必填	类型	备注
id	True	String	产品ID
name	True	String	产品名称，32个字符以内
description	True	String	产品描述，250个字符以内
link_type	True	Int	设备连接类型
mode	False	String	产品的型号，长度在64个字符以内
is_release	True	Boolean	是否发布，布尔值，true或false
is_registerable	True	Boolean	是否允许用户注册设备
is_active_register	True	Boolean	是否允许通过激活注册设备
is_allow_multi_admin	True	Boolean	否允许设备多个管理员
create_time	False	String	产品创建时间
user_role_authority	False	String	普通用户对设备的权限，默认RW
type	True	Int	产品类型
quota	True	Int	设备配额总数，整数
scan_mode	True	Int	扫描订阅策略，枚举值
pics	True	Array	产品图片列表
qrcode	True	String	产品二维码
extend	True	Object	扩展属性
device_type	True	String	设备类型
is_gateway_device	True	Boolean	是否为网关设备
categories	False	List<String>	产品品类
visibility	False	String	产品可见权限
is_home_product	True	Boolean	是否为首页产品
browse_time	False	String	最近浏览时间
os_type	True	Int	os类型
platform_categories	False	LIst<String>	平台产品分类
device_source	False	String	设备接入来源，枚举值：atandard：标准；ali_iot：阿里IoT；华为：huawei_iot；涂鸦：tuya；京东：jd；京东小京鱼：jd_whale；
mac_to_upper_case	False	Boolean	设备MAC是否转为大写，默认true
thing_model_group	False	String	物模型分组代码
thing_model_category	False	String	物模型品类代码
thing_model_type	False	String	物模型类型代码
gateway_setting	False	Object	网关选项设置，当is_gateway_device=true时，使用该字段进行网关选项设置
gateway_setting.reset_unbind_sub	False	Boolean	启用网关重置解绑子设备，默认为true
log_switch	False	Boolean	设备日志采集开关
total_device	False	Int	设备总数

返回示例：

{
    "thing_model_id": "njgc2k05fepkk5hi",
    "description": "",
    "is_registerable": false,
    "device_type": "Unkown",
    "is_third_party": false,
    "type": 0,
    "mode": "x",
    "qrcode": "",
    "mac_to_upper_case": true,
    "is_allow_multi_admin": false,
    "is_device_reset_clean_data": true,
    "node_type": 0,
    "scan_mode": 1,
    "quota": 100,
    "id": "16086ac2ec23200916086ac2ec23c601",
    "categories": [],
    "is_release": false,
    "pics": [
        ""
    ],
    "total_device": 3,
    "thing_model_group": "",
    "thing_model_category": "",
    "thing_model_type": "",
    "user_role_authority": "",
    "gateway_setting":{
      "reset_unbind_sub": false
    },
    "log_switch": false,
    "create_time": "2021-10-25T10:09:39.645Z",
    "visibility": 0,
    "is_active_register": false,
    "platform_categories": [],
    "browse_time": "2021-10-25T10:13:10.178Z",
    "link_type": 1,
    "extend": {},
    "is_home_product": false,
    "thing_model_source": -1,
    "is_gateway_device": false,
    "is_allow_sync": false,
    "os_type": "Other",
    "name": "测试-产品A",
    "device_source": "atandard",
    "cm_protocol_type": "6.5"
}

错误码	描述
-	-

5.2获取产品列表

5.2.1 获取产品列表

接口描述

应用场景: 提供给其他终端（例如：APP，PC端）展示产品列表。

接口限制：B端用户权限。

返回信息：产品基础信息，产品的设备类型，是否网关设备，产品下设备总数等。

请求方式

POST

请求地址

/v2/products

请求头

名称	必填	类型	备注
Access-Token	true	String	访问Token（B端用户权限）
Content-Type	true	String	application/json

请求参数

名称	必填	类型	备注
offset	false	int	从某个偏移量开始请求，默认为0
limit	false	Int	请求的条目数量，默认为10
order	false	Array	可以指定通过设备默认的某个字段排序，desc降序，asc升序
filter	False	List<String>	指定返回字段（键值对）
query	False	Object	查询条件，可以根据不同字段加上不同的比较指令来查询，查询条件字段包含设备所有默认字段，不支持扩展属性字段，支持比较指令包含如下: $in：包含于该列表任意一个值 $lt：小于该字段值 $lte：小于或等于字段值 $gt：大于该字段值 $gte：大于或等于该字段值 $like：模糊匹配该字段值

请求示例：

{
    "offset": "0",
    "limit": "10",
    "filter": [
        "id",
        "name",
        "description",
        "link_type",
        "mode",
        "is_release",
        "is_registerable",
        "is_active_register",
        "is_allow_multi_admin",
        "create_time",
        "user_role_authority",
        "type",
        "quota",
        "scan_mode",
        "pics",
        "qrcode",
        "extend",
        "device_type",
        "is_gateway_device",
        "categories",
        "visibility",
        "is_home_product",
        "browse_time",
        "os_type",
        "platform_categories",
        "device_source",
        "mac_to_upper_case",
        "thing_model_group",
        "thing_model_category",
        "thing_model_type",
        "gateway_setting",
        "log_switch",
        "total_device"
    ],
    "query": {
        "name": {
            "$eq": "..."
        }
    },
    "order": {
        "name": "desc"
    }
}

返回参数说明

名称	必填	类型	备注
count	True	Int	符合条件的总数
list	True	Array	本次返回列表
id	True	String	产品ID
name	True	String	产品名称，32个字符以内
description	True	String	产品描述，250个字符以内
link_type	True	Int	设备连接类型
mode	False	String	产品的型号，长度在64个字符以内
is_release	True	Boolean	是否发布，布尔值，true或false
is_registerable	True	Boolean	是否允许用户注册设备
is_active_register	True	Boolean	是否允许通过激活注册设备
is_allow_multi_admin	True	Boolean	否允许设备多个管理员
create_time	False	String	产品创建时间
user_role_authority	False	String	普通用户对设备的权限，默认RW
type	True	Int	产品类型
quota	True	Int	设备配额总数，整数
scan_mode	True	Int	扫描订阅策略，枚举值
pics	True	Array	产品图片列表
qrcode	True	String	产品二维码
extend	True	Map<String,Object>	扩展属性键值对
device_type	True	String	`设备类型`
is_gateway_device	True	Boolean	是否为网关设备
categories	False	List<String>	产品品类
visibility	False	String	产品可见权限
is_home_product	True	Boolean	是否为首页产品
browse_time	False	String	最近浏览时间
os_type	True	Int	os类型
platform_categories	False	List<String>	平台产品分类
device_source	False	String	设备接入来源，枚举值：atandard：标准；ali_iot：阿里IoT；华为：huawei_iot；涂鸦：tuya；京东：jd；京东小京鱼：jd_whale；
mac_to_upper_case	False	Boolean	设备MAC是否转为大写，默认true
thing_model_group	False	String	物模型分组代码
thing_model_category	False	String	物模型品类代码
thing_model_type	False	String	物模型类型代码
gateway_setting	False	Object	网关选项设置，当is_gateway_device=true时，使用该字段进行网关选项设置
gateway_setting.reset_unbind_sub	False	Boolean	启用网关重置解绑子设备，默认为true
log_switch	False	Boolean	设备日志采集开关
total_device	False	Boolean	设备总数

返回示例：

{
    "count": 53,
    "list": [
        {
            "description": "",
            "user_role_authority": "",
            "is_registerable": true,
            "device_type": "VideoSurveillance",
            "is_third_party": false,
            "type": 0,
            "mode": "",
            "qrcode": "",
            "device_source": "",
            "thing_model_group": "",
            "thing_model_type": "",
            "gateway_setting":{
              "reset_unbind_sub": false
            },
            "mac_to_upper_case": true,
            "thing_model_group": "",
            "is_allow_multi_admin": true,
            "is_device_reset_clean_data": true,
            "node_type": 0,
            "scan_mode": 2,
            "quota": 100,
            "id": "160002bb5d9e0001160002bb5d9e0e01",
            "categories": [],
            "is_release": false,
            "pics": [],
            "gateway_setting":{
              "reset_unbind_sub": false
            },
            "thing_model_template_id": "5d79e7f76fb0bd486ac4c51b",
            "log_switch": true,
            "create_time": "2019-10-22T17:42:31.61Z",
            "visibility": 0,
            "is_active_register": true,
            "platform_categories": [],
            "browse_time": "2021-09-14T11:53:42.127Z",
            "link_type": 1,
            "extend": {
              "a": 1,
              "b": "qwe"
            },
            "is_home_product": false,
            "thing_model_source": 1,
            "is_gateway_device": false,
            "os_type": "Other",
            "name": "视频产品-测试",
            "cm_protocol_type": "6.5",
            "total_device": 19
        }
    ]
}

错误码	描述
4001001	参数验证不通过
4001002	参数不能为空

5.3物模型定义

5.3.1 获取产品物模型

接口描述

应用场景: 提供给其他终端（例如：APP，PC端）展示产品物模型，用于设备控制。

接口限制：B端用户权限。

返回信息：产品下物模型信息，包括物模型属性，服务和事件。

请求方式

GET

请求地址

/v2/things/device_tml?product_id={product_id}

请求头

名称	必填	类型	备注
Access-Token	true	String	访问Token（B端用户权限、C端用户授权）
Content-Type	true	String	application/json

请求参数

名称	必填	类型	备注
-	-	-	-

请求示例：

无

返回参数说明

名称	必填	类型	备注
xnms	True	string	保留字段，标识物模型ID
id	True	string	物模型ID
version	True	string	保留字段，物模型版本，默认为2
attributes	True	Array	属性列表
attributes.field	True	String	属性字段名
attributes.field_name	True	Object	字段描述显示
attributes.field_name.cn	True	String	字段中文显示名称
attributes.field_name.en	True	String	字段英文显示名称
attributes.type	True	Object	类型信息
attributes.type.type	True	String	数据类型
attributes.type.specs	False	Object	规格信息
attributes.type.specs.{key}	False	String	不同规格描述
attributes.min	False	Int	字段最小值
attributes.max	False	Int	字段最大值
attributes.symbol	False	String	符号
attributes.default	False	String	默认值
attributes.access	True	String	访问权限，支持3种，r:读；w:写；rw:读写；
events	True	Array	事件列表
events.event	True	String	事件名
events.event_name	True	Object	事件名描述显示
events.event_name.cn	True	String	事件名中文描述
events.event_name.en	True	String	事件名英文描述
events.extra	True	Array	事件附加信息
events.extra.field	True	String	附加信息字段名
events.extra.field_name	True	Object	附加信息字段描述显示
events.extra.field_name.cn	True	String	附加信息字段中文描述
events.extra.field_name.en	True	String	附加信息字段英文描述
events.extra.type	True	Object	附加信息字段类型信息
events.extra.type.type	True	String	附加信息字段数据类型
events.extra.type.specs	False	Object	附加信息字段规格信息
events.extra.type.specs.{key}	False	String	附加信息字段规格信息
events.extra.require	True	Boolean	附加信息字段是否必须
events.extra.min	False	Int	附加信息字段最小值
events.extra.max	False	Int	附加信息字段最大值
services	True	Array	服务列表
services.service	True	String	服务名，用于调用
services.service_name	True	Object	服务名称描述显示
services.service_name.cn	True	String	服务名称中文描述
services.service_name.en	True	String	服务名称英文描述
services.input	True	Array	服务调用输入参数列表
services.input.field	True	String	输入参数字段名
services.input.field_name	True	String	输入参数字段描述
services.input.field_name.cn	True	String	输入参数中文描述
services.input.field_name.en	True	String	输入参数英文描述
services.input.type	True	Object	输入参数字段类型信息
services.input.type.type	True	String	输入参数字段数据类型
services.input.type.specs	False	Object	输入参数字段规格信息
services.input.type.specs.{key}	False	String	输入参数字段规格信息
services.input.require	True	Boolean	输入参数字段是否必须
services.output	True	Array	服务调用输出参数列表
services.output.field	True	String	输出参数字段名
services.output.field_name	True	Object	输出参数字段描述
services.output.field_name.cn	True	String	输出参数中文描述
services.output.field_name.en	True	String	输出参数英文描述
services.output.type	True	Object	输出参数字段类型信息
services.output.type.type	True	String	输出参数字段数据类型
services.output.type.specs	False	Object	输出参数字段规格信息
services.output.type.specs.{key}	False	String	输出参数字段规格信息
services.ouput.require	True	Boolean	输出参数字段是否必须

返回示例：

{
		"version":"2",
		"id":"...",
    "xnms": "....",
    "attributes": [
        {
            "field": "state",
            "field_name": {
                "cn": "工作状态",
                "en": "work state"
            },
            "type": {
                "type": "int",
                "specs": {
                    "1": "正常",
                    "2": "异常"
                }
            },
            "min": "1",
            "max": "2",
            "symbol": "-",
            "default": "1",
            "access": "r/w/rw"
        }
    ],
    "events": [
        {
            "event": "attribute_sync",
            "event_name": {
                "cn": "属性上报事件",
                "en": "attribute sync event"
            },
            "extra": [
                {
                    "field": "state",
                    "field_name": {
                        "cn": "工作状态",
                        "en": "work state"
                    },
                    "type": {
                        "specs": {
                            "1": "正常",
                            "2": "异常"
                        },
                        "type": "bool"
                    },
                    "require": false,
                    "min": "最小值",
                    "max": "最大值"
                }
            ]
        }
    ],
    "services": [
        {
            "service": "set",
            "service_name": {
                "cn": "设置属性",
                "en": "set attribute"
            },
            "input": [
                {
                    "field": "target_state",
                    "field_name": {
                        "cn": "工作状态",
                        "en": "work state"
                    },
                    "type": {
                        "specs": {
                            "1": "正常",
                            "2": "异常"
                        },
                        "type": "int"
                    },
                    "require": false
                }
            ],
            "code": {
                "specs": {
                    "200": "成功",
                    "202": "设备不在线",
                    "203": "设备未响应",
                    "400": "参数错误",
                    "403": "签名错误",
                    "503": "系统出错"
                }
            },
            "output": [
                {
                    "field": "result",
                    "field_name": {
                        "cn": "调用结果",
                        "en": "call result"
                    },
                    "type": {
                        "specs": {
                            "true": "成功",
                            "false": "失败"
                        },
                        "type": "bool"
                    },
                    "require": false
                }
            ]
        }
    ]
}

错误码	描述
4001001	参数验证不通过
4001002	参数不能为空

上次更新：2024-05-09